---
type: integration
title: '@astrojs/tailwind'
description: Astro 프로젝트에서 @astrojs/tailwind 통합을 사용하는 방법을 알아보세요.
githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/tailwind/'
category: other
i18nReady: true
---

import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';

이 **[Astro 통합][astro-integration]** 은 Tailwind 구성 파일에 대한 지원과 함께 프로젝트의 모든 `.astro` 파일 및 [프레임워크 컴포넌트](/ko/guides/framework-components/)에 [Tailwind의](https://tailwindcss.com/) 유틸리티 CSS 클래스를 제공합니다.

## 왜 Tailwind인가?

Tailwind를 사용하면 CSS를 작성하는 대신 유틸리티 클래스를 사용할 수 있습니다. 이러한 유틸리티 클래스는 대부분 특정 CSS 속성 설정과 일대일입니다. 예를 들어 요소에 `text-lg`를 추가하는 것은 CSS에서 `font-size: 1.125rem`을 설정하는 것과 같습니다. 미리 정의된 유틸리티 클래스를 사용하면 스타일을 작성하고 유지하는 것이 더 쉬울 수도 있습니다!

사전 정의된 설정이 마음에 들지 않으면 프로젝트의 디자인 요구 사항에 맞게 [Tailwind 구성 파일을 맞춤설정](https://tailwindcss.com/docs/configuration)할 수 있습니다. 예를 들어 디자인의 "큰 텍스트"가 실제로 `2rem`인 경우 [lg 글꼴 크기 설정](https://tailwindcss.com/docs/font-size#customizing-your-theme)을 `2rem`으로 변경할 수 있습니다.

Tailwind는 컴포넌트 파일에서 `<style>` 태그를 지원하지 않는 React, Preact, Solid 컴포넌트에 스타일을 추가하는 데에도 좋은 선택입니다.

참고: 동일한 파일에서 Tailwind와 다른 스타일 지정 방법 (예: Styled Components)을 모두 사용하는 것은 일반적으로 권장되지 않습니다.

## 설치

Astro에는 공식 통합 설정을 자동화하는 `astro add` 명령이 포함되어 있습니다. 원하는 경우 대신 [통합을 수동으로 설치](#수동-설치)할 수 있습니다.

새 터미널 창에서 다음 명령 중 하나를 실행합니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npx astro add tailwind
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm astro add tailwind
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn astro add tailwind
  ```
  </Fragment>
</PackageManagerTabs>

문제가 발생하면 [GitHub에서 언제든지 보고](https://github.com/withastro/astro/issues)하고 아래 수동 설치 단계를 시도해 보세요.

### 수동 설치

먼저 패키지 관리자를 사용하여 `@astrojs/tailwind` 및 `tailwindcss` 패키지를 설치합니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm install @astrojs/tailwind tailwindcss
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm add @astrojs/tailwind tailwindcss
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn add @astrojs/tailwind tailwindcss
  ```
  </Fragment>
</PackageManagerTabs>

그런 다음 `integrations` 속성을 사용하여 Astro 구성 파일에 통합을 적용합니다.

```js ins={2} ins="tailwind()" title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  // ...
  integrations: [tailwind()],
});
```

그런 다음 프로젝트의 루트 디렉터리에 `tailwind.config.mjs` 파일을 만듭니다. 다음 명령을 사용하여 기본 구성 파일을 생성할 수 있습니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npx tailwindcss init
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm dlx tailwindcss init
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn dlx tailwindcss init
  ```
  </Fragment>
</PackageManagerTabs>

마지막으로 `tailwind.config.mjs` 파일에 다음 기본 구성을 추가하세요.

```js ins={3} title="tailwind.config.mjs" "content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}']"
/** @type {import('tailwindcss').Config} */
export default {
  content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
  theme: {
    extend: {},
  },
  plugins: [],
};
```

## 사용하기

통합을 설치하면 Tailwind의 유틸리티 클래스를 즉시 사용할 수 있습니다. Tailwind 사용 방법을 알아보려면 [Tailwind 문서](https://tailwindcss.com/docs/utility-first)로 이동하세요. 사용해보고 싶은 유틸리티 클래스가 있으면 프로젝트의 HTML 요소에 추가하세요!

[Autoprefixer](https://github.com/postcss/autoprefixer) 역시 개발 모드와 프로덕션 빌드에서 자동으로 설정되므로 Tailwind 클래스는 이전 브라우저에서 작동합니다.

## 구성

### Tailwind 구성

빠른 설치 지침을 사용하고 각 프롬프트에 yes라고 답한 경우 프로젝트의 루트 디렉터리에 `tailwind.config.mjs` 파일이 표시됩니다. Tailwind 구성 변경에 이 파일을 사용하세요. [Tailwind 문서](https://tailwindcss.com/docs/configuration)에서 이 파일을 사용하여 Tailwind를 맞춤설정하는 방법을 알아볼 수 있습니다.

없는 경우 자체 `tailwind.config.(js|cjs|mjs|ts|mts|cts)` 파일을 루트 디렉터리에 추가하면 통합에서 해당 구성을 사용합니다. 이미 다른 프로젝트에 Tailwind를 구성했고 해당 설정을 이 프로젝트로 가져오려는 경우 유용할 수 있습니다.

### 통합 구성

Astro Tailwind 통합은 Astro와 Tailwind 간 통신을 처리하며 자체 옵션이 있습니다. 프로젝트의 통합 설정이 있는 `astro.config.mjs` 파일 (Tailwind 구성 파일이 *아님*)에서 이를 변경하세요.

#### 구성 파일

이전에는 `@astrojs/tailwind` v3에서 `config.path`로 알려졌습니다. 구성을 업데이트하려면 [v4 변경 로그](https://github.com/withastro/astro/blob/main/packages/integrations/tailwind/CHANGELOG.md#400)를 참조하세요.

기본 `tailwind.config.(js|cjs|mjs|ts|mts|cts)` 대신 다른 Tailwind 구성 파일을 사용하려면 이 통합의 `configFile` 옵션을 사용하여 해당 파일의 위치를 ​​지정하세요. `configFile`이 상대적인 경우 현재 작업 디렉터리를 기준으로 탐색합니다.

:::caution
공식 Tailwind VSCode 확장과 같이 Tailwind와 통합되는 다른 도구에 문제가 발생할 수 있으므로 이를 변경하는 것은 권장되지 않습니다.
:::

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  // ...
  integrations: [
    tailwind({
      // 예: Tailwind 구성 파일에 대한 맞춤 경로 제공
      configFile: './custom-config.mjs',
    }),
  ],
});
```

#### applyBaseStyles

이전에는 `@astrojs/tailwind` v3에서 `config.applyBaseStyles`로 알려졌습니다. 구성을 업데이트하려면 [v4 변경 로그](https://github.com/withastro/astro/blob/main/packages/integrations/tailwind/CHANGELOG.md#400)를 참조하세요.

기본적으로 통합은 프로젝트의 모든 페이지에서 기본 `base.css` 파일을 가져옵니다. 이 기본 CSS 파일에는 세 가지 주요 `@tailwind` 지시어가 포함되어 있습니다.

```css title="base.css"
/* 통합의 기본 삽입된 base.css 파일 */
@tailwind base;
@tailwind components;
@tailwind utilities;
```

이 기본 동작을 비활성화하려면 `applyBaseStyles`를 `false`로 설정하세요. 이는 자신만의 `base.css` 파일을 정의해야 하는 경우 (예를 들어 [`@layer` 지시어](https://tailwindcss.com/docs/functions-and-directives#layer)를 포함하기 위해) 유용할 수 있습니다. 프로젝트의 모든 페이지에서 `base.css`를 가져오지 않으려는 경우에도 유용할 수 있습니다.

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  // ...
  integrations: [
    tailwind({
      // 예: 모든 페이지에 기본 `base.css` 가져오기를 삽입하는 것을 비활성화합니다.
      // 사용자 정의 `base.css`를 정의 및/또는 가져와야 하는 경우 유용합니다.
      applyBaseStyles: false,
    }),
  ],
});
```

이제 [여러분의 base.css를 로컬 스타일시트로 가져올 수 있습니다](/ko/guides/styling/#로컬-스타일시트-가져오기).

#### nesting

Tailwind의 구문과 함께 중첩된 CSS 선언을 작성할 수 있도록 [`tailwindcss/nesting` PostCSS 플러그인](https://tailwindcss.com/docs/using-with-preprocessors#nesting)을 적용하려면 `true`로 설정하세요. 이 옵션은 기본적으로 `false`입니다.

```js ins="nesting: true"
// astro.config.mjs
import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  integrations: [
    tailwind({
      // 예: Tailwind 구문과 함께 중첩된 CSS 선언 작성 허용
      nesting: true,
    }),
  ],
});
```

## 예시

* [Astro Tailwind Starter](https://github.com/withastro/astro/tree/latest/examples/with-tailwindcss?on=github)를 사용하면 Tailwind를 사용하여 스타일링하는 프로젝트의 기반을 마련하고 실행할 수 있습니다.
* Astro의 홈페이지는 Tailwind를 사용합니다. [Tailwind 구성 파일](https://github.com/withastro/astro.build/blob/main/tailwind.config.ts) 또는 [예시 컴포넌트](https://github.com/withastro/astro.build/blob/main/src/components/Checkbox.astro)를 확인하세요.
* [Astro Ink](https://github.com/one-aalam/astro-ink), [Sarissa Blog](https://github.com/iozcelik/SarissaBlogAstroStarter), [Astro Tech Blog](https://github.com/nicdun/astro-tech-blog), [Creek](https://github.com/robertguss/Astro-Theme-Creek) 테마는 스타일링에 Tailwind를 사용합니다.
* 더 많은 예시를 보려면 [GitHub에서 Astro Tailwind 프로젝트를 찾아보세요](https://github.com/search?q=%22%40astrojs%2Ftailwind%22%3A+path%3A%2Fpackage.json\&type=code)!

## 문제 해결

### `@apply` 지시어가 포함된 클래스가 존재하지 않습니다.

Astro, Vue, Svelte 또는 다른 컴포넌트 통합의 `<style>` 태그에서 `@apply` 지시어를 사용하면 사용자 정의 Tailwind 클래스가 존재하지 않는다는 오류가 생성되어 빌드가 실패할 수 있습니다.

```sh
error   The `text-special` class does not exist. If `text-special` is a custom class, make sure it is defined within a `@layer` directive.
```

[전역 스타일시트에서 @layer 지시어를 사용하는 대신](https://tailwindcss.com/docs/functions-and-directives#using-apply-with-per-component-css) Tailwind 구성에 플러그인을 추가하여 맞춤 스타일을 정의하여 문제를 해결하세요.

```js title="tailwind.config.mjs"
export default {
  // ...
  plugins: [
    function ({ addComponents, theme }) {
      addComponents({
        '.btn': {
          padding: theme('spacing.4'),
          margin: 'auto',
        },
      });
    },
  ],
};
```

### 클래스 기반 수정자는 `@apply` 지시어와 함께 작동하지 않습니다.

수정자가 있는 특정 Tailwind 클래스는 여러 요소의 클래스 결합에 의존합니다. 예를 들어 `group-hover:text-gray`는 `.group:hover .text-gray`로 컴파일됩니다. Astro `<style>` 태그의 `@apply` 지시어와 함께 사용되면 컴파일된 스타일이 `.astro` 파일의 어떤 마크업과도 일치하지 않기 때문에 빌드 출력에서 ​​제거됩니다. Vue 및 Svelte와 같은 범위 지정 스타일을 지원하는 프레임워크 컴포넌트에서도 동일한 문제가 발생할 수 있습니다.

이 문제를 해결하려면 대신 인라인 클래스를 사용할 수 있습니다.

```html "text-black group-hover:text-gray"
<p class="text-black group-hover:text-gray">Astro</p>
```

### 기타 문제

* 설치가 작동하지 않는 것 같으면 개발 서버를 다시 시작해 보세요.
* 파일을 편집하고 저장했는데 사이트 업데이트가 제대로 표시되지 않으면 페이지를 새로 고쳐보세요.
* 페이지를 새로 고쳐도 미리보기가 업데이트되지 않거나 새로 설치해도 작동하지 않는 것 같으면 개발 서버를 다시 시작하세요.

도움이 필요하시면 [Discord](https://astro.build/chat)의 `#support` 채널을 확인하세요. 우리의 친절한 지원팀 멤버들이 도와드리겠습니다!

통합에 대한 자세한 내용은 [Astro 통합 문서][astro-integration]를 확인하실 수도 있습니다.

[astro-integration]: /ko/guides/integrations-guide/

[astro-ui-frameworks]: /ko/guides/framework-components/#using-framework-components
